DG Kernel Documentation

IFrame interface is used only to control orientation and position of different frames in the DInsight software. A frame is actually a local system of coordinates. It is uniquely determined by 3D point of its origin in global coordinates and 3D vectors of its axes. To be valid, vectors of the axes must have length 1.0 and be orthogonal to each other. IFrame interface is inherited from and hence has all methods of I3DObject interface. Additional methods allow more flexibility in manipulation of the frame.

Currently IFrame is can be queried only either from IView or ISection interface. In case of IView IFrame represents current position of the global frame with respect to the point of view. More precisely IFrame controls coordinates of the global frame relative to the Eye Frame. When IFrame is queried from ISection it acts as an extension of I3DObject and exposes position and orientation of the object in 3D space.

To create a new (standalone) frame to for some calculations call IDIObjGenerator.Create or IDIObjGenerator.Create2 with eType parameter set to eObjTypeFrame member of EObjectType enumeration. The returned IUnknown reference has actual type IFrame and can be safely cast to or queried from to convert to IFrame type.

HRESULT RotateStd(double dAng, int nAxis)

Parameters

dAng - [in] Angle of rotation in degrees .

nAxis - [in] 0-based index of the axis around which the rotation will be performed

Returns

S_OK in case of success.

Remarks

Changes orientation of the frame by rotating it around its specified axis

HRESULT SetAxes(int nAxis0, DIVect* axis0, int nAxis1, DIVect* axis1, bool bOrientation)

Parameters:

nAxis0 - [in] 0-based index of axis, which will be changed to axis0.

axis0 - [in] 3D vector which will be set as nAxis0-th axis of the frame. DIVect type is described in Basic Types.

nAxis1 - [in] 0-based index of axis, which will be changed to axis1.

axis1 - [in] 3D vector which will be set as nAxis1-th axis of the frame. DIVect type is described in Basic Types. Supplying zero vector for this parameter means the axis is not specified. The method will select an arbitrary orthogonal axis.

bOrientation - [in] normally is true. If bOrientation is true the resulting axes will have normal positive orientation like standard Cartesian system of coordinates. Otherwise direction of the remaining axis will be changed to opposite in the end of the method call (See remarks).

Returns

S_OK in case of success.

DISP_E_PARAMNOTOPTIONAL in case axis0 or axis1 are zero vectors or have the same direction
Remarks

This methods is provided for the case when simpler RotateStd method is not satisfactory. Call this method to set directions of axes of the frame. DIVect type is described in Basic Types. Normally axis0 and axis1 are orthogonal vectors. They must not have the same direction otherwise the method will fail with DISP_E_PARAMNOTOPTIONAL return code. If axis0 and axis1 are not orthogonal orthogonalization is applied to axis1. Supplying zero vector for axis1 parameter means the axis is not specified. The method will select an arbitrary orthogonal axis. In addition to that, both vectors are normalized to make their lengths equal to 1.0. The third remaining axis is calculated using the supplied ones and condition that it must be orthogonal to both of them and have its length equal to 1.0.
bOrientation is normally is true. In this case the resulting axes will have normal positive orientation like standard Cartesian system of coordinates. Otherwise direction of the remaining axis will be changed to opposite in the end of the method call.

HRESULT Reset()

Return Values

S_OK in case of success

Remarks

Resets the frame to its default: After this call the frame will coincide with the global frame .